IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/il/ilWarp.z/ilWarp

Text File | 2002-10-03 | 17.0 KB | 397 lines

iiiillllWWWWaaaarrrrpppp((((3333))))          IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll          iiiillllWWWWaaaarrrrpppp((((3333))))



NNNNAAAAMMMMEEEE
     iiiillllWWWWaaaarrrrpppp - general 3D warp operations

IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM
     ilWatchedObject

HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
     #include <il/ilWarp.h>

CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     The ilWarp class encapsulates general 3D coordinate transformations for
     use by ilWarpImg and subclasses thereof.  A particular warp is defined by
     overriding the eeeevvvvaaaallll() virtual.  Several other virtuals can be overridden
     to enable more efficient batch evaluation, inversion, composition, and so
     forth.

     The ilWarp class contains one pure virtual method, ccccooooppppyyyy(), so it is not
     possible to construct an ilWarp object, and any concrete derived class
     must implement the copy virtual.  The ilWarpImg operator relies on the
     copy method to maintain an internal copy of a user-supplied warp.

     ilWarp is derived from ilWatchedObject.  This makes it possible to set a
     "dynamic" warp object on an ilWarpImg --- one that is not copied, but
     instead "watched" for any changes.  When the warp changes, the ilWarpImg
     responds appropriately.  This implies that any class that is derived from
     ilWarp must trigger the appropriate notification whenever it is changed.
     In particular the non-const virtual methods iiiiddddeeeennnnttttiiiittttyyyy(), iiiinnnnvvvveeeerrrrtttt(),
     ccccoooommmmppppoooosssseeee(), and iiiinnnnffffeeeerrrr() should call the protected method wwwwaaaarrrrppppCCCChhhhaaaannnnggggeeeedddd().
     (However, if any of these methods fails and leaves the warp unchanged the
     wwwwaaaarrrrppppCCCChhhhaaaannnnggggeeeedddd() method should not be called.)

     ilWarp provides several alternative means to evaluate the warp that it
     specifies.  The principal one is eeeevvvvaaaallll() which must be defined by a
     derived class.  The others are xxxx(), yyyy(), and zzzz(), which evaluate the
     components of the warp, ddddxxxx(), ddddyyyy(), and ddddzzzz(), which evaluate the Jacobian
     of the warp,

CCCCLLLLAAAASSSSSSSS MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN SSSSUUUUMMMMMMMMAAAARRRRYYYY
     CCCCooooppppyyyyiiiinnnngggg

          virtual ilWarp* copy()

     WWWWaaaarrrrpppp eeeevvvvaaaalllluuuuaaaattttiiiioooonnnn mmmmeeeetttthhhhooooddddssss

          virtual void eval(float& x, float& y, float& z, float u,
                            float v, float w)
          void eval(float& x, float& y, float u, float v)
          virtual float x(float u, float v=0, float w=0)
          virtual float y(float u, float v=0, float w=0)
          virtual float z(float u, float v=0, float w=0)
          virtual void dx(float& x, float& y, float& z, float u,
                          float v=0, float w=0)



                                                                        PPPPaaaaggggeeee 1111






iiiillllWWWWaaaarrrrpppp((((3333))))          IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll          iiiillllWWWWaaaarrrrpppp((((3333))))



          virtual void dy(float& x, float& y, float& z, float u,
                          float v=0, float w=0)
          virtual void dz(float& x, float& y, float& z, float u,
                          float v=0, float w=0)
          virtual ilStatus getBBox(iflXYZfloat& min, iflXYZfloat& max,
                                   int su, int sv, int sw, int nu,
                                   int nv, int nw)
          ilStatus getBBox(iflXYZfloat& min, iflXYZfloat& max, int su,
                           int sv, int nu, int nv)
          virtual void evalVector(float upos, float vpos, float ustep,
                                  iflXYfloat *addrs, int count,
                                  float wpos=0)
          void findRoot(const iflXYZfloat& xy, iflXYZfloat& uv,
                        int tries, float xyzTol, float uvwTol)
          iflXYZfloat operator()(float u, float v, float w)
          iflXYfloat operator()(float u, float v)
          iflXYZfloat operator()(const iflXYZfloat& p)
          iflXYfloat operator()(const iflXYfloat& p)

     WWWWaaaarrrrpppp mmmmaaaannnniiiippppuuuullllaaaattttiiiioooonnnn

          virtual void identity()
          virtual ilStatus invert(ilWarpQuality quality=ilWarpBest,
                                  float ulo=0, float uhi=1, float vlo=0,
                                  float vhi=1, float wlo=0, float whi=0)
          virtual ilStatus compose(const ilWarp& other,
                                   ilWarpQuality quality=ilWarpBest)
          virtual ilStatus infer(ilTiePointList& tiePoints,
                                 ilWarpQuality quality=ilWarpBest)
          virtual int minimumNumberOfTies()

     AAAAlllltttteeeerrrraaaattttiiiioooonnnn ccccaaaallllllllbbbbaaaacccckkkk mmmmeeeetttthhhhooooddddssss

          void warpChanged()  _p_r_o_t_e_c_t_e_d


FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS
     ccccoooommmmppppoooosssseeee(((())))

          virtual ilStatus compose(const ilWarp& other,
                                   ilWarpQuality quality=ilWarpBest)


          Compose this warp with another. This object is updated to reflect
          the composite transformation equivalent to applying
          (*this)(other(p)).  The default implementation returns ilFAILED.  If
          quality is ilWarpExact, then the method should return ilOKAY only if
          the precise composition can be computed.  Otherwise it should return
          ilFAILED.  If quality is ilWarpBest, then the method can return
          ilAPPROXIMATE if only an approximate composition can be computed.
          If the composition operation fails, then this object should be
          unmodified.



                                                                        PPPPaaaaggggeeee 2222






iiiillllWWWWaaaarrrrpppp((((3333))))          IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll          iiiillllWWWWaaaarrrrpppp((((3333))))



     ccccooooppppyyyy(((())))

          virtual ilWarp* copy()


          This is a pure virtual method that allocates a duplicate of the warp
          object.  It is used by ilWarpImg to maintain an internal copy of the
          warp passed by ilWarpImg::setWarp().

     ddddxxxx(((())))

          virtual void dx(float& x, float& y, float& z, float u,
                          float v=0, float w=0)


          Evaluate the partial derivatives (dx/du,dy/du,dz/du) of the warp
          function at the point (u,v,w).  The default implementation returns
          zeros.

     ddddyyyy(((())))

          virtual void dy(float& x, float& y, float& z, float u,
                          float v=0, float w=0)


          Evaluate the partial derivatives (dx/dv,dy/dv,dz/dv) of the warp
          function at the point (u,v,w).  The default implementation returns
          zeros.

     ddddzzzz(((())))

          virtual void dz(float& x, float& y, float& z, float u,
                          float v=0, float w=0)


          Evaluate the partial derivatives (dx/dw,dy/dw,dz/dw) of the warp
          function at the point (u,v,w).  The default implementation returns
          zeros.

     eeeevvvvaaaallll(((())))

          virtual void eval(float& x, float& y, float& z, float u,
                            float v, float w)


          void eval(float& x, float& y, float u, float v)


          This is a convenience method to evaluate all three coordinates of
          the transformation and return the result in a structure.  The 2D
          version assumes that w = 0.




                                                                        PPPPaaaaggggeeee 3333






iiiillllWWWWaaaarrrrpppp((((3333))))          IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll          iiiillllWWWWaaaarrrrpppp((((3333))))



     eeeevvvvaaaallllVVVVeeeeccccttttoooorrrr(((())))

          virtual void evalVector(float upos, float vpos, float ustep,
                                  iflXYfloat *addrs, int count,
                                  float wpos=0)


          Perform the equivalent of

          for (int i=0; i<count; i++) {
              float z;
              eval(addrs[i].x, addrs[i].y, z, upos+ustep*i, vpos, wpos);
          }


          for use by the ilWarpImg address generation function.  This function
          should be optimized as much as possible by derived classes in order
          to achieve good ilWarpImg performance.

     ffffiiiinnnnddddRRRRooooooootttt(((())))

          void findRoot(const iflXYZfloat& xyz, iflXYZfloat& uvw,
                        int tries, float xyzTol, float uvwTol)


          Search numerically for the solution to

              xyz = warp(uvw).


          The search terminates when one of the following conditions is met:
          (1) the number of iterations exceeds _t_r_i_e_s, (2) the difference
          between successive approximations is <= _x_y_z_T_o_l, or (3) the
          difference between (_x_y_z) and warp(_u_v_w) is <= _u_v_w_T_o_l.

     ggggeeeettttBBBBBBBBooooxxxx(((())))

          ilStatus getBBox(iflXYZfloat& min, iflXYZfloat& max, int su,
                           int sv, int nu, int nv)
          virtual ilStatus getBBox(iflXYZfloat& min, iflXYZfloat& max,
                                   int su, int sv, int sw, int nu,
                                   int nv, int nw)


          Return the bounding box of the mapped rectangle with corners
          (su,sv,sw) and (su+nu,sv+nv,sw+nw).  The lower-left and upper-right
          vertices of the box are returned in the min and max structures,
          respectively.  The default implementation is by sampling the
          boundary of the input rectangle at a fixed granularity and computing
          the bounding box of the mapped set of sample points.  It returns
          ilOKAY if the computation is successful and ilFAILED otherwise.  The
          2D version assumes sw == 0 and nw == 1.



                                                                        PPPPaaaaggggeeee 4444






iiiillllWWWWaaaarrrrpppp((((3333))))          IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll          iiiillllWWWWaaaarrrrpppp((((3333))))



     iiiiddddeeeennnnttttiiiittttyyyy(((())))

          virtual void identity()


          Sets the warp to the identity function.  The default implementation
          does nothing.

     iiiinnnnffffeeeerrrr(((())))

          virtual ilStatus infer(ilTiePointList& tiePoints,
                                 ilWarpQuality quality=ilWarpBest)


          Infer the warp from a set of point correspondences in the input and
          output spaces.  See ccccoooommmmppppoooosssseeee() for the interpretation of the quality
          argument.  The default implementation returns ilFAILED.  This method
          must be defined by any subclass that will be used by ilTieWarpImg.

     iiiinnnnvvvveeeerrrrtttt(((())))

          virtual ilStatus invert(ilWarpQuality quality=ilWarpBest,
                                  float ulo=0, float uhi=1, float vlo=0,
                                  float vhi=1, float wlo=0, float whi=0)


          Invert the warp over the domain specified by the rectangle
          (ulo,vlo,wlo) to (uhi,vhi,whi).  The accuracy of the inverse outside
          this rectangle is undefined.  See ccccoooommmmppppoooosssseeee() for the interpretation
          of the quality argument.  The default implementation uses iiiinnnnffffeeeerrrr() to
          guess the inverse via a set of tie points.

     mmmmiiiinnnniiiimmmmuuuummmmNNNNuuuummmmbbbbeeeerrrrOOOOffffTTTTiiiieeeessss(((())))

          virtual int minimumNumberOfTies()


          Return the minimum number of tie points necessary to infer the warp.
          The default implementation returns INT_MAX.

     ooooppppeeeerrrraaaattttoooorrrr(((())))

          iflXYZfloat operator()(const iflXYZfloat& p)


          iflXYZfloat operator()(float u, float v, float w)


          iflXYfloat operator()(const iflXYfloat& p)






                                                                        PPPPaaaaggggeeee 5555






iiiillllWWWWaaaarrrrpppp((((3333))))          IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll          iiiillllWWWWaaaarrrrpppp((((3333))))



          iflXYfloat operator()(float u, float v)


          The () operator provides convenient means to evaluate the warp
          function at a point.  wwwwaaaarrrrppppCCCChhhhaaaannnnggggeeeedddd(((())))

          void warpChanged()  _p_r_o_t_e_c_t_e_d


          This method should be called by a derived class whenever the warp is
          altered.  It is used by ilWarpImg to notice changes in a dynamic
          warp.

     xxxx(((())))

          virtual float x(float u, float v=0, float w=0)


          Evaluate the x component of the warp function at a point.  The
          default implementation is to return u.  This virtual should be
          overridden by any derived class that transforms the x component.

     yyyy(((())))

          virtual float y(float u, float v=0, float w=0)


          Evaluate the y component of the warp function at a point.  The
          default implementation is to return v.  This virtual should be
          overridden by any derived class that transforms the y component.

     zzzz(((())))

          virtual float z(float u, float v=0, float w=0)


          Evaluate the z component of the warp function at a point.  The
          default implementation is to return w.  This virtual should be
          overridden by any derived class that transforms the z component.

IIIINNNNHHHHEEEERRRRIIIITTTTEEEEDDDD MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
   IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm iiiillllWWWWaaaattttcccchhhheeeeddddOOOObbbbjjjjeeeecccctttt
     addWatchCallback(), doWatchCallbacks(), removeWatchCallback()


SSSSEEEEEEEE AAAALLLLSSSSOOOO
     ilWarpImg, ilPolyWarp, ilAffineWarp, ilPolyDef, ilTieWarpImg








                                                                        PPPPaaaaggggeeee 6666